PBAllocateSync

PBAllocateSync
Header:	Files.h		Carbon status:	Supported

Allocates additional blocks to an open file.

OSErr PBAllocateSync (
    ParmBlkPtr paramBlock
);

paramBlock: A pointer to a basic File Manager parameter block.

function result: A result code.

DISCUSSION

The relevant fields of the parameter block are:

ioCompletion

On input, a pointer to a completion routine.
ioResult

On output, the result code of the function.
ioRefNum

On input, a file reference number for the file to which to allocate additional blocks.
ioReqCount

On input, the number of bytes to allocate.
ioActCount

On output, the number of bytes actually allocated, rounded up to the nearest multiple of the allocation block size.

The PBAllocateSync function adds ioReqCount bytes to the specified file and sets the physical end-of-file to 1 byte beyond the last block allocated. If there isn’t enough empty space on the volume to satisfy the allocation request, PBAllocateSync allocates the rest of the space on the volume and returns dskFulErr as its function result.

If the total number of requested bytes is unavailable, PBAllocateSync allocates whatever space, contiguous or not, is available. To force the allocation of the entire requested space as a contiguous piece, call PBAllocContigSync instead.

The File Manager automatically allocates file blocks if you move the logical end-of-file past the physical end-of-file, and it automatically deallocates unneeded blocks from a file if you move the logical end-of-file to a position more than one allocation block before the current physical end-of-file. Consequently, you do not in general need to be concerned with allocating or deallocating file blocks. However, you can improve file block contiguity if you use the PBAllocateSync function to preallocate file blocks. This is most useful if you know in advance how big a file is likely to become.

PBAllocateSync is not supported by AppleShare volumes. Instead, use SetEOF or PBSetEOFSync to extend a file by setting the end-of-file.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.